This step is required only if you're using the back-end API without policy enforcement enabled. If you don't have access to an API gateway, skip ahead to the mobile application setup.

The policy enforcement entity, which is either an API gateway or code within the API itself, is responsible for ensuring that only authenticated and authorized clients get access to the back-end API. For authentication, the access tokens that are acquired by the clients are validated and checked against the IDP-provided public certificate keys. For fine grained authorization, this example uses group membership, which is included in the access token as part of the group claim.

The following rules are enforced in the example:

Public (access_token validation only)

POST /reset

GET /shop

GET /shop​/{shopId}

GET /shop​/{shopId}​/products

GET /shop​/{shopId}​/stock

Employee (access_token validation + group claim that includes "employee" and/or "manager" group)

GET /warehouse

GET /warehouse​/{warehouseId}

GET /warehouse​/{warehouseId}​/stock

Manager (access_token validation + group claim that includes "manager" group)

POST /warehouse​/{warehouseId}​/stock​/{stockId}​/move​/{shopId}

To ensure that the enforcement point cannot be circumvented, the communication between the enforcement point and the back-end API needs to be secure. This can be done by your network configuration, but a more common approach is to use mutual TLS authentication with client and server certificates. However, this example does not feature this functionality.

Apigee API gateway

You can sign up for an Apigee trial account: https://login.apigee.com/sign__up

Configure Apigee API gateway

The example configuration is available for reference on GitHub:

https://github.com/ThalesGroup/sta-api-access-management/tree/master/API%20Gateway/Apigee

You need to manually configure tenant-specific information.

Create an API proxy

First we need to create an API proxy without any authentication or authorization enforcement between Apigee and the back-end API.

In a production setup, you need to prevent the circumvention of the API proxy. This is usually done by using mutual TLS authentication between the API proxy and the back-end API. To simplify this setup, the communication channel between the API proxy and the back-end API is not secured.

1. To set up a new API proxy, log on to the Apigee Admin console and select +Proxy.

   

2. Create a new Reverse proxy.

   

3. Provide a unique name and the back-end API details.

   

4. Select Pass through (no authorization) in the Common policies section. Validation of access tokens and claim validation is added in a later step.

   

5. Depending on your API endpoint, select secure, default, or both. It is recommended to use the secure option.

   

6. In the Summary screen, select a deployment option. For test purposes, the test target is sufficient.

   

7. After the proxy is deployed, copy and save the URL, which acts as your base URL for all API requests.

   

   You can now use any REST API client against the above URL to validate that the passthrough proxy is working as expected.

   Depending on the back-end API configuration, no authentication or authorization is required. For example, a call to base_url/shop should yield a result. So everybody who knows about the Apigee API endpoint can issue commands to the back-end API.

   

Add JWT validation

The next step is to ensure that only authenticated and authorized clients get access to the API. To do this, add a policy that requires a valid JWT token in the API request.

Before you can add this policy, you need to configure either a client credentials or an authorization code flow application. These applications also contain the required configuration strings for the JWT validation step.

The JWT validation policy performs the validation locally, which is less compute-intensive, hence faster and more performant. A more secure way to validate access tokens is to use the STA token introspection endpoint, which ensures that an access token is not revoked. That setup is outside of the scope of this scenario.

1. To add a JWT validation policy, select the newly created proxy and switch to the DEVELOP tab.

2. Select the PreFlow in the left pane and then select +Step.

   

3. Select the Verify-JWT policy and then select Add.

   

4. Update the policy configuration as indicated in the XML below. You can find JWKS and Issuer values in the well known configuration URL of the application that you created in STA.

   

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<VerifyJWT async="false" continueOnError="false" enabled="true" name="Validate-STA-access_token">
    <DisplayName>Validate STA access_token</DisplayName>
    <Algorithm>RS256</Algorithm>
    <PublicKey>
        <JWKS uri="https://spedemo-sasidp.stademo.com/auth/realms/A1BC2DEFG3-STA/protocol/openid-connect/certs"/>
    </PublicKey>
    <Issuer>https://spedemo-sasidp.stademo.com/auth/realms/A1BC2DEFG3-STA</Issuer>
</VerifyJWT>

After you enable this policy and validate authentication or authorization, the following error is sent back when the authorization header is missing. In the error message, variable(null) indicates that the authorization header is missing in the request.

{
    "fault": {
        "faultstring": "Failed to Resolve Variable : policy(Validate-STA-access_token) variable(null)",
        "detail": {
            "errorcode": "steps.jwt.FailedToResolveVariable"
        }
    }
}

Policy enforcement using claims validation

To add claim inspection to specific flows, add a customer flow with a condition. To provide a well-understood error message, create a RaiseFault policy first. This policy is raised when the condition in the flow is not met.

1. In the Policies section, select +, add a RaiseFault Mediation, and adjust the definition using the code block below.

   

   <?xml version="1.0" encoding="UTF-8" standalone="yes"?>
   <RaiseFault async="false" continueOnError="false" enabled="true" name="Require-Manager-or-Employee-Group-Claim">
       <DisplayName>Require Manager or Employee Group Claim</DisplayName>
       <Properties/>
       <FaultResponse>
           <Set>
               <Headers/>
               <Payload contentType="text/plain">{
       "message": "Unauthorized. You need to login as an employee or manager to list warehouses".
   }</Payload>
               <StatusCode>401</StatusCode>
               <ReasonPhrase>Unauthorized</ReasonPhrase>
           </Set>
       </FaultResponse>
       <IgnoreUnresolvedVariables>true</IgnoreUnresolvedVariables>
   </RaiseFault>
   

2. Add a custom flow with a condition for the /warehouse** path, which is supposed to be accessible by only employees or managers.

   Using /warehouse** ensures that the flow applies to all requests that start with warehouse. If you don't use the wildcards, then you need to configure the following settings for each endpoint separately.

   

3. Drag the previously configured JWT validation policy and the RaiseFault policy into the custom flow.

   

4. Update the XML in Endpoint Default to include a condition that raises the fault policy in case the group claim cannot be found in the request. Validate-STA-access_token is the name of the JWT validation policy that you defined.

   <Condition>
      NOT(
           jwt.Validate-STA-access_token.decoded.claim.group == "employee"
           OR
           jwt.Validate-STA-access_token.decoded.claim.group == "manager"
         )
   </Condition>
   

   

   The call to the warehouse API now fails if the access token does not contain a group claim with the values employee or manager.

   

5. To ensure that only managers can move inventory, add a new RaiseFault policy and custom flow for POST /warehouse** with a condition that requires a manager.

   <Condition>
      NOT(
           jwt.Validate-STA-access_token.decoded.claim.group == "manager"
         )
   </Condition>
   

   

Amazon API gateway

Amazon provides a free trial tier for the AWS Gateway:

https://aws.amazon.com/api-gateway/pricing/

AWS Lambda Sample Function

This demo uses an AWS Lambda function to validate an OIDC-based access mechanism. This Lambda function is used to create an Authorizer in an Amazon API Gateway. Finally, add the Authorizer to the API endpoints that you want to protect.

Configure the Amazon API gateway

To configure the Amazon API gateway, refer to the documentation for the Amazon API Gateway application that you added in STA.